home *** CD-ROM | disk | FTP | other *** search
/ Clickx 115 / Clickx 115.iso / software / tools / windows / tails-i386-0.16.iso / live / filesystem.squashfs / usr / lib / ruby / 1.8 / cgi.rb < prev    next >
Encoding:
Ruby Source  |  2009-12-13  |  73.7 KB  |  2,314 lines

  1. # cgi.rb - cgi support library
  2. # Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
  3. # Copyright (C) 2000  Information-technology Promotion Agency, Japan
  4. #
  5. # Author: Wakou Aoyama <wakou@ruby-lang.org>
  6. #
  7. # Documentation: Wakou Aoyama (RDoc'd and embellished by William Webber) 
  8. # == Overview
  9. #
  10. # The Common Gateway Interface (CGI) is a simple protocol
  11. # for passing an HTTP request from a web server to a
  12. # standalone program, and returning the output to the web
  13. # browser.  Basically, a CGI program is called with the
  14. # parameters of the request passed in either in the
  15. # environment (GET) or via $stdin (POST), and everything
  16. # it prints to $stdout is returned to the client.
  17. # This file holds the +CGI+ class.  This class provides
  18. # functionality for retrieving HTTP request parameters,
  19. # managing cookies, and generating HTML output.  See the
  20. # class documentation for more details and examples of use.
  21. #
  22. # The file cgi/session.rb provides session management
  23. # functionality; see that file for more details.
  24. #
  25. # See http://www.w3.org/CGI/ for more information on the CGI
  26. # protocol.
  27.  
  28. raise "Please, use ruby 1.5.4 or later." if RUBY_VERSION < "1.5.4"
  29.  
  30. require 'English'
  31.  
  32. # CGI class.  See documentation for the file cgi.rb for an overview
  33. # of the CGI protocol.
  34. #
  35. # == Introduction
  36. #
  37. # CGI is a large class, providing several categories of methods, many of which
  38. # are mixed in from other modules.  Some of the documentation is in this class,
  39. # some in the modules CGI::QueryExtension and CGI::HtmlExtension.  See
  40. # CGI::Cookie for specific information on handling cookies, and cgi/session.rb
  41. # (CGI::Session) for information on sessions.
  42. #
  43. # For queries, CGI provides methods to get at environmental variables,
  44. # parameters, cookies, and multipart request data.  For responses, CGI provides
  45. # methods for writing output and generating HTML.
  46. #
  47. # Read on for more details.  Examples are provided at the bottom.
  48. #
  49. # == Queries
  50. #
  51. # The CGI class dynamically mixes in parameter and cookie-parsing
  52. # functionality,  environmental variable access, and support for
  53. # parsing multipart requests (including uploaded files) from the
  54. # CGI::QueryExtension module.
  55. #
  56. # === Environmental Variables
  57. #
  58. # The standard CGI environmental variables are available as read-only
  59. # attributes of a CGI object.  The following is a list of these variables:
  60. #
  61. #
  62. #   AUTH_TYPE               HTTP_HOST          REMOTE_IDENT
  63. #   CONTENT_LENGTH          HTTP_NEGOTIATE     REMOTE_USER
  64. #   CONTENT_TYPE            HTTP_PRAGMA        REQUEST_METHOD
  65. #   GATEWAY_INTERFACE       HTTP_REFERER       SCRIPT_NAME
  66. #   HTTP_ACCEPT             HTTP_USER_AGENT    SERVER_NAME
  67. #   HTTP_ACCEPT_CHARSET     PATH_INFO          SERVER_PORT
  68. #   HTTP_ACCEPT_ENCODING    PATH_TRANSLATED    SERVER_PROTOCOL
  69. #   HTTP_ACCEPT_LANGUAGE    QUERY_STRING       SERVER_SOFTWARE
  70. #   HTTP_CACHE_CONTROL      REMOTE_ADDR
  71. #   HTTP_FROM               REMOTE_HOST
  72. #
  73. #
  74. # For each of these variables, there is a corresponding attribute with the
  75. # same name, except all lower case and without a preceding HTTP_.  
  76. # +content_length+ and +server_port+ are integers; the rest are strings.
  77. #
  78. # === Parameters
  79. #
  80. # The method #params() returns a hash of all parameters in the request as
  81. # name/value-list pairs, where the value-list is an Array of one or more
  82. # values.  The CGI object itself also behaves as a hash of parameter names 
  83. # to values, but only returns a single value (as a String) for each 
  84. # parameter name.
  85. #
  86. # For instance, suppose the request contains the parameter 
  87. # "favourite_colours" with the multiple values "blue" and "green".  The
  88. # following behaviour would occur:
  89. #
  90. #   cgi.params["favourite_colours"]  # => ["blue", "green"]
  91. #   cgi["favourite_colours"]         # => "blue"
  92. #
  93. # If a parameter does not exist, the former method will return an empty
  94. # array, the latter an empty string.  The simplest way to test for existence
  95. # of a parameter is by the #has_key? method.
  96. #
  97. # === Cookies
  98. #
  99. # HTTP Cookies are automatically parsed from the request.  They are available
  100. # from the #cookies() accessor, which returns a hash from cookie name to
  101. # CGI::Cookie object.
  102. #
  103. # === Multipart requests
  104. #
  105. # If a request's method is POST and its content type is multipart/form-data, 
  106. # then it may contain uploaded files.  These are stored by the QueryExtension
  107. # module in the parameters of the request.  The parameter name is the name
  108. # attribute of the file input field, as usual.  However, the value is not
  109. # a string, but an IO object, either an IOString for small files, or a
  110. # Tempfile for larger ones.  This object also has the additional singleton
  111. # methods:
  112. #
  113. # #local_path():: the path of the uploaded file on the local filesystem
  114. # #original_filename():: the name of the file on the client computer
  115. # #content_type():: the content type of the file
  116. #
  117. # == Responses
  118. #
  119. # The CGI class provides methods for sending header and content output to
  120. # the HTTP client, and mixes in methods for programmatic HTML generation
  121. # from CGI::HtmlExtension and CGI::TagMaker modules.  The precise version of HTML
  122. # to use for HTML generation is specified at object creation time.
  123. #
  124. # === Writing output
  125. #
  126. # The simplest way to send output to the HTTP client is using the #out() method.
  127. # This takes the HTTP headers as a hash parameter, and the body content
  128. # via a block.  The headers can be generated as a string using the #header()
  129. # method.  The output stream can be written directly to using the #print()
  130. # method.
  131. #
  132. # === Generating HTML
  133. #
  134. # Each HTML element has a corresponding method for generating that
  135. # element as a String.  The name of this method is the same as that
  136. # of the element, all lowercase.  The attributes of the element are 
  137. # passed in as a hash, and the body as a no-argument block that evaluates
  138. # to a String.  The HTML generation module knows which elements are
  139. # always empty, and silently drops any passed-in body.  It also knows
  140. # which elements require matching closing tags and which don't.  However,
  141. # it does not know what attributes are legal for which elements.
  142. #
  143. # There are also some additional HTML generation methods mixed in from
  144. # the CGI::HtmlExtension module.  These include individual methods for the
  145. # different types of form inputs, and methods for elements that commonly
  146. # take particular attributes where the attributes can be directly specified
  147. # as arguments, rather than via a hash.
  148. #
  149. # == Examples of use
  150. # === Get form values
  151. #   require "cgi"
  152. #   cgi = CGI.new
  153. #   value = cgi['field_name']   # <== value string for 'field_name'
  154. #     # if not 'field_name' included, then return "".
  155. #   fields = cgi.keys            # <== array of field names
  156. #   # returns true if form has 'field_name'
  157. #   cgi.has_key?('field_name')
  158. #   cgi.has_key?('field_name')
  159. #   cgi.include?('field_name')
  160. # CAUTION! cgi['field_name'] returned an Array with the old 
  161. # cgi.rb(included in ruby 1.6)
  162. # === Get form values as hash
  163. #   require "cgi"
  164. #   cgi = CGI.new
  165. #   params = cgi.params
  166. # cgi.params is a hash.
  167. #   cgi.params['new_field_name'] = ["value"]  # add new param
  168. #   cgi.params['field_name'] = ["new_value"]  # change value
  169. #   cgi.params.delete('field_name')           # delete param
  170. #   cgi.params.clear                          # delete all params
  171. # === Save form values to file
  172. #   require "pstore"
  173. #   db = PStore.new("query.db")
  174. #   db.transaction do
  175. #     db["params"] = cgi.params
  176. #   end
  177. # === Restore form values from file
  178. #   require "pstore"
  179. #   db = PStore.new("query.db")
  180. #   db.transaction do
  181. #     cgi.params = db["params"]
  182. #   end
  183. # === Get multipart form values
  184. #   require "cgi"
  185. #   cgi = CGI.new
  186. #   value = cgi['field_name']   # <== value string for 'field_name'
  187. #   value.read                  # <== body of value
  188. #   value.local_path            # <== path to local file of value
  189. #   value.original_filename     # <== original filename of value
  190. #   value.content_type          # <== content_type of value
  191. # and value has StringIO or Tempfile class methods.
  192. # === Get cookie values
  193. #   require "cgi"
  194. #   cgi = CGI.new
  195. #   values = cgi.cookies['name']  # <== array of 'name'
  196. #     # if not 'name' included, then return [].
  197. #   names = cgi.cookies.keys      # <== array of cookie names
  198. # and cgi.cookies is a hash.
  199. # === Get cookie objects
  200. #   require "cgi"
  201. #   cgi = CGI.new
  202. #   for name, cookie in cgi.cookies
  203. #     cookie.expires = Time.now + 30
  204. #   end
  205. #   cgi.out("cookie" => cgi.cookies) {"string"}
  206. #   cgi.cookies # { "name1" => cookie1, "name2" => cookie2, ... }
  207. #   require "cgi"
  208. #   cgi = CGI.new
  209. #   cgi.cookies['name'].expires = Time.now + 30
  210. #   cgi.out("cookie" => cgi.cookies['name']) {"string"}
  211. # === Print http header and html string to $DEFAULT_OUTPUT ($>)
  212. #   require "cgi"
  213. #   cgi = CGI.new("html3")  # add HTML generation methods
  214. #   cgi.out() do
  215. #     cgi.html() do
  216. #       cgi.head{ cgi.title{"TITLE"} } +
  217. #       cgi.body() do
  218. #         cgi.form() do
  219. #           cgi.textarea("get_text") +
  220. #           cgi.br +
  221. #           cgi.submit
  222. #         end +
  223. #         cgi.pre() do
  224. #           CGI::escapeHTML(
  225. #             "params: " + cgi.params.inspect + "\n" +
  226. #             "cookies: " + cgi.cookies.inspect + "\n" +
  227. #             ENV.collect() do |key, value|
  228. #               key + " --> " + value + "\n"
  229. #             end.join("")
  230. #           )
  231. #         end
  232. #       end
  233. #     end
  234. #   end
  235. #   # add HTML generation methods
  236. #   CGI.new("html3")    # html3.2
  237. #   CGI.new("html4")    # html4.01 (Strict)
  238. #   CGI.new("html4Tr")  # html4.01 Transitional
  239. #   CGI.new("html4Fr")  # html4.01 Frameset
  240. #
  241. class CGI
  242.  
  243.   # :stopdoc:
  244.  
  245.   # String for carriage return
  246.   CR  = "\015"
  247.  
  248.   # String for linefeed
  249.   LF  = "\012"
  250.  
  251.   # Standard internet newline sequence
  252.   EOL = CR + LF
  253.  
  254.   REVISION = '$Id: cgi.rb 26086 2009-12-14 02:40:07Z shyouhei $' #:nodoc:
  255.  
  256.   NEEDS_BINMODE = true if /WIN/ni.match(RUBY_PLATFORM) 
  257.  
  258.   # Path separators in different environments.
  259.   PATH_SEPARATOR = {'UNIX'=>'/', 'WINDOWS'=>'\\', 'MACINTOSH'=>':'}
  260.  
  261.   # HTTP status codes.
  262.   HTTP_STATUS = {
  263.     "OK"                  => "200 OK",
  264.     "PARTIAL_CONTENT"     => "206 Partial Content",
  265.     "MULTIPLE_CHOICES"    => "300 Multiple Choices",
  266.     "MOVED"               => "301 Moved Permanently",
  267.     "REDIRECT"            => "302 Found",
  268.     "NOT_MODIFIED"        => "304 Not Modified",
  269.     "BAD_REQUEST"         => "400 Bad Request",
  270.     "AUTH_REQUIRED"       => "401 Authorization Required",
  271.     "FORBIDDEN"           => "403 Forbidden",
  272.     "NOT_FOUND"           => "404 Not Found",
  273.     "METHOD_NOT_ALLOWED"  => "405 Method Not Allowed",
  274.     "NOT_ACCEPTABLE"      => "406 Not Acceptable",
  275.     "LENGTH_REQUIRED"     => "411 Length Required",
  276.     "PRECONDITION_FAILED" => "412 Precondition Failed",
  277.     "SERVER_ERROR"        => "500 Internal Server Error",
  278.     "NOT_IMPLEMENTED"     => "501 Method Not Implemented",
  279.     "BAD_GATEWAY"         => "502 Bad Gateway",
  280.     "VARIANT_ALSO_VARIES" => "506 Variant Also Negotiates"
  281.   }
  282.  
  283.   # Abbreviated day-of-week names specified by RFC 822
  284.   RFC822_DAYS = %w[ Sun Mon Tue Wed Thu Fri Sat ]
  285.  
  286.   # Abbreviated month names specified by RFC 822
  287.   RFC822_MONTHS = %w[ Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ]
  288.  
  289.   # :startdoc:
  290.  
  291.   def env_table 
  292.     ENV
  293.   end
  294.  
  295.   def stdinput
  296.     $stdin
  297.   end
  298.  
  299.   def stdoutput
  300.     $DEFAULT_OUTPUT
  301.   end
  302.  
  303.   private :env_table, :stdinput, :stdoutput
  304.  
  305.   # URL-encode a string.
  306.   #   url_encoded_string = CGI::escape("'Stop!' said Fred")
  307.   #      # => "%27Stop%21%27+said+Fred"
  308.   def CGI::escape(string)
  309.     string.gsub(/([^ a-zA-Z0-9_.-]+)/n) do
  310.       '%' + $1.unpack('H2' * $1.size).join('%').upcase
  311.     end.tr(' ', '+')
  312.   end
  313.  
  314.  
  315.   # URL-decode a string.
  316.   #   string = CGI::unescape("%27Stop%21%27+said+Fred")
  317.   #      # => "'Stop!' said Fred"
  318.   def CGI::unescape(string)
  319.     string.tr('+', ' ').gsub(/((?:%[0-9a-fA-F]{2})+)/n) do
  320.       [$1.delete('%')].pack('H*')
  321.     end
  322.   end
  323.  
  324.  
  325.   # Escape special characters in HTML, namely &\"<>
  326.   #   CGI::escapeHTML('Usage: foo "bar" <baz>')
  327.   #      # => "Usage: foo "bar" <baz>"
  328.   def CGI::escapeHTML(string)
  329.     string.gsub(/&/n, '&').gsub(/\"/n, '"').gsub(/>/n, '>').gsub(/</n, '<')
  330.   end
  331.  
  332.  
  333.   # Unescape a string that has been HTML-escaped
  334.   #   CGI::unescapeHTML("Usage: foo "bar" <baz>")
  335.   #      # => "Usage: foo \"bar\" <baz>"
  336.   def CGI::unescapeHTML(string)
  337.     string.gsub(/&(amp|quot|gt|lt|\#[0-9]+|\#x[0-9A-Fa-f]+);/n) do
  338.       match = $1.dup
  339.       case match
  340.       when 'amp'                 then '&'
  341.       when 'quot'                then '"'
  342.       when 'gt'                  then '>'
  343.       when 'lt'                  then '<'
  344.       when /\A#0*(\d+)\z/n       then
  345.         if Integer($1) < 256
  346.           Integer($1).chr
  347.         else
  348.           if Integer($1) < 65536 and ($KCODE[0] == ?u or $KCODE[0] == ?U)
  349.             [Integer($1)].pack("U")
  350.           else
  351.             "&##{$1};"
  352.           end
  353.         end
  354.       when /\A#x([0-9a-f]+)\z/ni then
  355.         if $1.hex < 128
  356.           $1.hex.chr
  357.         else
  358.           if $1.hex < 65536 and ($KCODE[0] == ?u or $KCODE[0] == ?U)
  359.             [$1.hex].pack("U")
  360.           else
  361.             "&#x#{$1};"
  362.           end
  363.         end
  364.       else
  365.         "&#{match};"
  366.       end
  367.     end
  368.   end
  369.  
  370.  
  371.   # Escape only the tags of certain HTML elements in +string+.
  372.   #
  373.   # Takes an element or elements or array of elements.  Each element
  374.   # is specified by the name of the element, without angle brackets.
  375.   # This matches both the start and the end tag of that element.
  376.   # The attribute list of the open tag will also be escaped (for
  377.   # instance, the double-quotes surrounding attribute values).
  378.   #
  379.   #   print CGI::escapeElement('<BR><A HREF="url"></A>', "A", "IMG")
  380.   #     # "<BR><A HREF="url"></A>"
  381.   #
  382.   #   print CGI::escapeElement('<BR><A HREF="url"></A>', ["A", "IMG"])
  383.   #     # "<BR><A HREF="url"></A>"
  384.   def CGI::escapeElement(string, *elements)
  385.     elements = elements[0] if elements[0].kind_of?(Array)
  386.     unless elements.empty?
  387.       string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/ni) do
  388.         CGI::escapeHTML($&)
  389.       end
  390.     else
  391.       string
  392.     end
  393.   end
  394.  
  395.  
  396.   # Undo escaping such as that done by CGI::escapeElement()
  397.   #
  398.   #   print CGI::unescapeElement(
  399.   #           CGI::escapeHTML('<BR><A HREF="url"></A>'), "A", "IMG")
  400.   #     # "<BR><A HREF="url"></A>"
  401.   # 
  402.   #   print CGI::unescapeElement(
  403.   #           CGI::escapeHTML('<BR><A HREF="url"></A>'), ["A", "IMG"])
  404.   #     # "<BR><A HREF="url"></A>"
  405.   def CGI::unescapeElement(string, *elements)
  406.     elements = elements[0] if elements[0].kind_of?(Array)
  407.     unless elements.empty?
  408.       string.gsub(/<\/?(?:#{elements.join("|")})(?!\w)(?:.|\n)*?>/ni) do
  409.         CGI::unescapeHTML($&)
  410.       end
  411.     else
  412.       string
  413.     end
  414.   end
  415.  
  416.  
  417.   # Format a +Time+ object as a String using the format specified by RFC 1123.
  418.   #
  419.   #   CGI::rfc1123_date(Time.now)
  420.   #     # Sat, 01 Jan 2000 00:00:00 GMT
  421.   def CGI::rfc1123_date(time)
  422.     t = time.clone.gmtime
  423.     return format("%s, %.2d %s %.4d %.2d:%.2d:%.2d GMT",
  424.                 RFC822_DAYS[t.wday], t.day, RFC822_MONTHS[t.month-1], t.year,
  425.                 t.hour, t.min, t.sec)
  426.   end
  427.  
  428.  
  429.   # Create an HTTP header block as a string.
  430.   #
  431.   # Includes the empty line that ends the header block.
  432.   #
  433.   # +options+ can be a string specifying the Content-Type (defaults
  434.   # to text/html), or a hash of header key/value pairs.  The following
  435.   # header keys are recognized:
  436.   #
  437.   # type:: the Content-Type header.  Defaults to "text/html"
  438.   # charset:: the charset of the body, appended to the Content-Type header.
  439.   # nph:: a boolean value.  If true, prepend protocol string and status code, and
  440.   #       date; and sets default values for "server" and "connection" if not
  441.   #       explicitly set.
  442.   # status:: the HTTP status code, returned as the Status header.  See the
  443.   #          list of available status codes below.
  444.   # server:: the server software, returned as the Server header.
  445.   # connection:: the connection type, returned as the Connection header (for 
  446.   #              instance, "close".
  447.   # length:: the length of the content that will be sent, returned as the
  448.   #          Content-Length header.
  449.   # language:: the language of the content, returned as the Content-Language
  450.   #            header.
  451.   # expires:: the time on which the current content expires, as a +Time+
  452.   #           object, returned as the Expires header.
  453.   # cookie:: a cookie or cookies, returned as one or more Set-Cookie headers.
  454.   #          The value can be the literal string of the cookie; a CGI::Cookie
  455.   #          object; an Array of literal cookie strings or Cookie objects; or a 
  456.   #          hash all of whose values are literal cookie strings or Cookie objects.
  457.   #          These cookies are in addition to the cookies held in the
  458.   #          @output_cookies field.
  459.   #
  460.   # Other header lines can also be set; they are appended as key: value.
  461.   # 
  462.   #   header
  463.   #     # Content-Type: text/html
  464.   # 
  465.   #   header("text/plain")
  466.   #     # Content-Type: text/plain
  467.   # 
  468.   #   header("nph"        => true,
  469.   #          "status"     => "OK",  # == "200 OK"
  470.   #            # "status"     => "200 GOOD",
  471.   #          "server"     => ENV['SERVER_SOFTWARE'],
  472.   #          "connection" => "close",
  473.   #          "type"       => "text/html",
  474.   #          "charset"    => "iso-2022-jp",
  475.   #            # Content-Type: text/html; charset=iso-2022-jp
  476.   #          "length"     => 103,
  477.   #          "language"   => "ja",
  478.   #          "expires"    => Time.now + 30,
  479.   #          "cookie"     => [cookie1, cookie2],
  480.   #          "my_header1" => "my_value"
  481.   #          "my_header2" => "my_value")
  482.   # 
  483.   # The status codes are:
  484.   # 
  485.   #   "OK"                  --> "200 OK"
  486.   #   "PARTIAL_CONTENT"     --> "206 Partial Content"
  487.   #   "MULTIPLE_CHOICES"    --> "300 Multiple Choices"
  488.   #   "MOVED"               --> "301 Moved Permanently"
  489.   #   "REDIRECT"            --> "302 Found"
  490.   #   "NOT_MODIFIED"        --> "304 Not Modified"
  491.   #   "BAD_REQUEST"         --> "400 Bad Request"
  492.   #   "AUTH_REQUIRED"       --> "401 Authorization Required"
  493.   #   "FORBIDDEN"           --> "403 Forbidden"
  494.   #   "NOT_FOUND"           --> "404 Not Found"
  495.   #   "METHOD_NOT_ALLOWED"  --> "405 Method Not Allowed"
  496.   #   "NOT_ACCEPTABLE"      --> "406 Not Acceptable"
  497.   #   "LENGTH_REQUIRED"     --> "411 Length Required"
  498.   #   "PRECONDITION_FAILED" --> "412 Precondition Failed"
  499.   #   "SERVER_ERROR"        --> "500 Internal Server Error"
  500.   #   "NOT_IMPLEMENTED"     --> "501 Method Not Implemented"
  501.   #   "BAD_GATEWAY"         --> "502 Bad Gateway"
  502.   #   "VARIANT_ALSO_VARIES" --> "506 Variant Also Negotiates"
  503.   # 
  504.   # This method does not perform charset conversion. 
  505.   #
  506.   def header(options = "text/html")
  507.  
  508.     buf = ""
  509.  
  510.     case options
  511.     when String
  512.       options = { "type" => options }
  513.     when Hash
  514.       options = options.dup
  515.     end
  516.  
  517.     unless options.has_key?("type")
  518.       options["type"] = "text/html"
  519.     end
  520.  
  521.     if options.has_key?("charset")
  522.       options["type"] += "; charset=" + options.delete("charset")
  523.     end
  524.  
  525.     options.delete("nph") if defined?(MOD_RUBY)
  526.     if options.delete("nph") or
  527.         (/IIS\/(\d+)/n.match(env_table['SERVER_SOFTWARE']) and $1.to_i < 5)
  528.       buf += (env_table["SERVER_PROTOCOL"] or "HTTP/1.0")  + " " +
  529.              (HTTP_STATUS[options["status"]] or options["status"] or "200 OK") +
  530.              EOL +
  531.              "Date: " + CGI::rfc1123_date(Time.now) + EOL
  532.  
  533.       unless options.has_key?("server")
  534.         options["server"] = (env_table['SERVER_SOFTWARE'] or "")
  535.       end
  536.  
  537.       unless options.has_key?("connection")
  538.         options["connection"] = "close"
  539.       end
  540.  
  541.       options.delete("status")
  542.     end
  543.  
  544.     if options.has_key?("status")
  545.       buf += "Status: " +
  546.              (HTTP_STATUS[options["status"]] or options["status"]) + EOL
  547.       options.delete("status")
  548.     end
  549.  
  550.     if options.has_key?("server")
  551.       buf += "Server: " + options.delete("server") + EOL
  552.     end
  553.  
  554.     if options.has_key?("connection")
  555.       buf += "Connection: " + options.delete("connection") + EOL
  556.     end
  557.  
  558.     buf += "Content-Type: " + options.delete("type") + EOL
  559.  
  560.     if options.has_key?("length")
  561.       buf += "Content-Length: " + options.delete("length").to_s + EOL
  562.     end
  563.  
  564.     if options.has_key?("language")
  565.       buf += "Content-Language: " + options.delete("language") + EOL
  566.     end
  567.  
  568.     if options.has_key?("expires")
  569.       buf += "Expires: " + CGI::rfc1123_date( options.delete("expires") ) + EOL
  570.     end
  571.  
  572.     if options.has_key?("cookie")
  573.       if options["cookie"].kind_of?(String) or
  574.            options["cookie"].kind_of?(Cookie)
  575.         buf += "Set-Cookie: " + options.delete("cookie").to_s + EOL
  576.       elsif options["cookie"].kind_of?(Array)
  577.         options.delete("cookie").each{|cookie|
  578.           buf += "Set-Cookie: " + cookie.to_s + EOL
  579.         }
  580.       elsif options["cookie"].kind_of?(Hash)
  581.         options.delete("cookie").each_value{|cookie|
  582.           buf += "Set-Cookie: " + cookie.to_s + EOL
  583.         }
  584.       end
  585.     end
  586.     if @output_cookies
  587.       for cookie in @output_cookies
  588.         buf += "Set-Cookie: " + cookie.to_s + EOL
  589.       end
  590.     end
  591.  
  592.     options.each{|key, value|
  593.       buf += key + ": " + value.to_s + EOL
  594.     }
  595.  
  596.     if defined?(MOD_RUBY)
  597.       table = Apache::request.headers_out
  598.       buf.scan(/([^:]+): (.+)#{EOL}/n){ |name, value|
  599.         warn sprintf("name:%s value:%s\n", name, value) if $DEBUG
  600.         case name
  601.         when 'Set-Cookie'
  602.           table.add(name, value)
  603.         when /^status$/ni
  604.           Apache::request.status_line = value
  605.           Apache::request.status = value.to_i
  606.         when /^content-type$/ni
  607.           Apache::request.content_type = value
  608.         when /^content-encoding$/ni
  609.           Apache::request.content_encoding = value
  610.         when /^location$/ni
  611.       if Apache::request.status == 200
  612.         Apache::request.status = 302
  613.       end
  614.           Apache::request.headers_out[name] = value
  615.         else
  616.           Apache::request.headers_out[name] = value
  617.         end
  618.       }
  619.       Apache::request.send_http_header
  620.       ''
  621.     else
  622.       buf + EOL
  623.     end
  624.  
  625.   end # header()
  626.  
  627.  
  628.   # Print an HTTP header and body to $DEFAULT_OUTPUT ($>)
  629.   #
  630.   # The header is provided by +options+, as for #header().
  631.   # The body of the document is that returned by the passed-
  632.   # in block.  This block takes no arguments.  It is required.
  633.   #
  634.   #   cgi = CGI.new
  635.   #   cgi.out{ "string" }
  636.   #     # Content-Type: text/html
  637.   #     # Content-Length: 6
  638.   #     #
  639.   #     # string
  640.   # 
  641.   #   cgi.out("text/plain") { "string" }
  642.   #     # Content-Type: text/plain
  643.   #     # Content-Length: 6
  644.   #     #
  645.   #     # string
  646.   # 
  647.   #   cgi.out("nph"        => true,
  648.   #           "status"     => "OK",  # == "200 OK"
  649.   #           "server"     => ENV['SERVER_SOFTWARE'],
  650.   #           "connection" => "close",
  651.   #           "type"       => "text/html",
  652.   #           "charset"    => "iso-2022-jp",
  653.   #             # Content-Type: text/html; charset=iso-2022-jp
  654.   #           "language"   => "ja",
  655.   #           "expires"    => Time.now + (3600 * 24 * 30),
  656.   #           "cookie"     => [cookie1, cookie2],
  657.   #           "my_header1" => "my_value",
  658.   #           "my_header2" => "my_value") { "string" }
  659.   # 
  660.   # Content-Length is automatically calculated from the size of
  661.   # the String returned by the content block.
  662.   #
  663.   # If ENV['REQUEST_METHOD'] == "HEAD", then only the header
  664.   # is outputted (the content block is still required, but it
  665.   # is ignored).
  666.   # 
  667.   # If the charset is "iso-2022-jp" or "euc-jp" or "shift_jis" then
  668.   # the content is converted to this charset, and the language is set 
  669.   # to "ja".
  670.   def out(options = "text/html") # :yield:
  671.  
  672.     options = { "type" => options } if options.kind_of?(String)
  673.     content = yield
  674.  
  675.     if options.has_key?("charset")
  676.       require "nkf"
  677.       case options["charset"]
  678.       when /iso-2022-jp/ni
  679.         content = NKF::nkf('-m0 -x -j', content)
  680.         options["language"] = "ja" unless options.has_key?("language")
  681.       when /euc-jp/ni
  682.         content = NKF::nkf('-m0 -x -e', content)
  683.         options["language"] = "ja" unless options.has_key?("language")
  684.       when /shift_jis/ni
  685.         content = NKF::nkf('-m0 -x -s', content)
  686.         options["language"] = "ja" unless options.has_key?("language")
  687.       end
  688.     end
  689.  
  690.     options["length"] = content.length.to_s
  691.     output = stdoutput
  692.     output.binmode if defined? output.binmode
  693.     output.print header(options)
  694.     output.print content unless "HEAD" == env_table['REQUEST_METHOD']
  695.   end
  696.  
  697.  
  698.   # Print an argument or list of arguments to the default output stream
  699.   #
  700.   #   cgi = CGI.new
  701.   #   cgi.print    # default:  cgi.print == $DEFAULT_OUTPUT.print
  702.   def print(*options)
  703.     stdoutput.print(*options)
  704.   end
  705.  
  706.   require "delegate"
  707.  
  708.   # Class representing an HTTP cookie.
  709.   #
  710.   # In addition to its specific fields and methods, a Cookie instance
  711.   # is a delegator to the array of its values.
  712.   #
  713.   # See RFC 2965.
  714.   #
  715.   # == Examples of use
  716.   #   cookie1 = CGI::Cookie::new("name", "value1", "value2", ...)
  717.   #   cookie1 = CGI::Cookie::new("name" => "name", "value" => "value")
  718.   #   cookie1 = CGI::Cookie::new('name'    => 'name',
  719.   #                              'value'   => ['value1', 'value2', ...],
  720.   #                              'path'    => 'path',   # optional
  721.   #                              'domain'  => 'domain', # optional
  722.   #                              'expires' => Time.now, # optional
  723.   #                              'secure'  => true      # optional
  724.   #                             )
  725.   # 
  726.   #   cgi.out("cookie" => [cookie1, cookie2]) { "string" }
  727.   # 
  728.   #   name    = cookie1.name
  729.   #   values  = cookie1.value
  730.   #   path    = cookie1.path
  731.   #   domain  = cookie1.domain
  732.   #   expires = cookie1.expires
  733.   #   secure  = cookie1.secure
  734.   # 
  735.   #   cookie1.name    = 'name'
  736.   #   cookie1.value   = ['value1', 'value2', ...]
  737.   #   cookie1.path    = 'path'
  738.   #   cookie1.domain  = 'domain'
  739.   #   cookie1.expires = Time.now + 30
  740.   #   cookie1.secure  = true
  741.   class Cookie < DelegateClass(Array)
  742.  
  743.     # Create a new CGI::Cookie object.
  744.     #
  745.     # The contents of the cookie can be specified as a +name+ and one
  746.     # or more +value+ arguments.  Alternatively, the contents can
  747.     # be specified as a single hash argument.  The possible keywords of
  748.     # this hash are as follows:
  749.     #
  750.     # name:: the name of the cookie.  Required.
  751.     # value:: the cookie's value or list of values.
  752.     # path:: the path for which this cookie applies.  Defaults to the
  753.     #        base directory of the CGI script.
  754.     # domain:: the domain for which this cookie applies.
  755.     # expires:: the time at which this cookie expires, as a +Time+ object.
  756.     # secure:: whether this cookie is a secure cookie or not (default to
  757.     #          false).  Secure cookies are only transmitted to HTTPS 
  758.     #          servers.
  759.     #
  760.     # These keywords correspond to attributes of the cookie object.
  761.     def initialize(name = "", *value)
  762.       if name.kind_of?(String)
  763.         @name = name
  764.         @value = value
  765.         %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
  766.         @path = ($1 or "")
  767.         @secure = false
  768.         return super(@value)
  769.       end
  770.  
  771.       options = name
  772.       unless options.has_key?("name")
  773.         raise ArgumentError, "`name' required"
  774.       end
  775.  
  776.       @name = options["name"]
  777.       @value = Array(options["value"])
  778.       # simple support for IE
  779.       if options["path"]
  780.         @path = options["path"]
  781.       else
  782.         %r|^(.*/)|.match(ENV["SCRIPT_NAME"])
  783.         @path = ($1 or "")
  784.       end
  785.       @domain = options["domain"]
  786.       @expires = options["expires"]
  787.       @secure = options["secure"] == true ? true : false
  788.  
  789.       super(@value)
  790.     end
  791.  
  792.     attr_accessor("name", "path", "domain", "expires")
  793.     attr_reader("secure", "value")
  794.  
  795.     # Set whether the Cookie is a secure cookie or not.
  796.     #
  797.     # +val+ must be a boolean.
  798.     def secure=(val)
  799.       @secure = val if val == true or val == false
  800.       @secure
  801.     end
  802.  
  803.     def value=(val)
  804.       @value.replace(Array(val))
  805.     end
  806.  
  807.     # Convert the Cookie to its string representation.
  808.     def to_s
  809.       buf = ""
  810.       buf += @name + '='
  811.  
  812.       buf += @value.map { |v| CGI::escape(v) }.join("&")
  813.  
  814.       if @domain
  815.         buf += '; domain=' + @domain
  816.       end
  817.  
  818.       if @path
  819.         buf += '; path=' + @path
  820.       end
  821.  
  822.       if @expires
  823.         buf += '; expires=' + CGI::rfc1123_date(@expires)
  824.       end
  825.  
  826.       if @secure == true
  827.         buf += '; secure'
  828.       end
  829.  
  830.       buf
  831.     end
  832.  
  833.   end # class Cookie
  834.  
  835.  
  836.   # Parse a raw cookie string into a hash of cookie-name=>Cookie
  837.   # pairs.
  838.   #
  839.   #   cookies = CGI::Cookie::parse("raw_cookie_string")
  840.   #     # { "name1" => cookie1, "name2" => cookie2, ... }
  841.   #
  842.   def Cookie::parse(raw_cookie)
  843.     cookies = Hash.new([])
  844.     return cookies unless raw_cookie
  845.  
  846.     raw_cookie.split(/[;,]\s?/).each do |pairs|
  847.       name, values = pairs.split('=',2)
  848.       next unless name and values
  849.       name = CGI::unescape(name)
  850.       values ||= ""
  851.       values = values.split('&').collect{|v| CGI::unescape(v) }
  852.       if cookies.has_key?(name)
  853.         values = cookies[name].value + values
  854.       end
  855.       cookies[name] = Cookie::new(name, *values)
  856.     end
  857.  
  858.     cookies
  859.   end
  860.  
  861.   # Parse an HTTP query string into a hash of key=>value pairs.
  862.   #
  863.   #   params = CGI::parse("query_string")
  864.   #     # {"name1" => ["value1", "value2", ...],
  865.   #     #  "name2" => ["value1", "value2", ...], ... }
  866.   #
  867.   def CGI::parse(query)
  868.     params = Hash.new([].freeze)
  869.  
  870.     query.split(/[&;]/n).each do |pairs|
  871.       key, value = pairs.split('=',2).collect{|v| CGI::unescape(v) }
  872.       if params.has_key?(key)
  873.         params[key].push(value)
  874.       else
  875.         params[key] = [value]
  876.       end
  877.     end
  878.  
  879.     params
  880.   end
  881.  
  882.   # Mixin module. It provides the follow functionality groups:
  883.   #
  884.   # 1. Access to CGI environment variables as methods.  See 
  885.   #    documentation to the CGI class for a list of these variables.
  886.   #
  887.   # 2. Access to cookies, including the cookies attribute.
  888.   #
  889.   # 3. Access to parameters, including the params attribute, and overloading
  890.   #    [] to perform parameter value lookup by key.
  891.   #
  892.   # 4. The initialize_query method, for initialising the above
  893.   #    mechanisms, handling multipart forms, and allowing the
  894.   #    class to be used in "offline" mode.
  895.   #
  896.   module QueryExtension
  897.  
  898.     %w[ CONTENT_LENGTH SERVER_PORT ].each do |env|
  899.       define_method(env.sub(/^HTTP_/n, '').downcase) do
  900.         (val = env_table[env]) && Integer(val)
  901.       end
  902.     end
  903.  
  904.     %w[ AUTH_TYPE CONTENT_TYPE GATEWAY_INTERFACE PATH_INFO
  905.         PATH_TRANSLATED QUERY_STRING REMOTE_ADDR REMOTE_HOST
  906.         REMOTE_IDENT REMOTE_USER REQUEST_METHOD SCRIPT_NAME
  907.         SERVER_NAME SERVER_PROTOCOL SERVER_SOFTWARE
  908.  
  909.         HTTP_ACCEPT HTTP_ACCEPT_CHARSET HTTP_ACCEPT_ENCODING
  910.         HTTP_ACCEPT_LANGUAGE HTTP_CACHE_CONTROL HTTP_FROM HTTP_HOST
  911.         HTTP_NEGOTIATE HTTP_PRAGMA HTTP_REFERER HTTP_USER_AGENT ].each do |env|
  912.       define_method(env.sub(/^HTTP_/n, '').downcase) do
  913.         env_table[env]
  914.       end
  915.     end
  916.  
  917.     # Get the raw cookies as a string.
  918.     def raw_cookie
  919.       env_table["HTTP_COOKIE"]
  920.     end
  921.  
  922.     # Get the raw RFC2965 cookies as a string.
  923.     def raw_cookie2
  924.       env_table["HTTP_COOKIE2"]
  925.     end
  926.  
  927.     # Get the cookies as a hash of cookie-name=>Cookie pairs.
  928.     attr_accessor("cookies")
  929.  
  930.     # Get the parameters as a hash of name=>values pairs, where
  931.     # values is an Array.
  932.     attr("params")
  933.  
  934.     # Set all the parameters.
  935.     def params=(hash)
  936.       @params.clear
  937.       @params.update(hash)
  938.     end
  939.  
  940.     def read_multipart(boundary, content_length)
  941.       params = Hash.new([])
  942.       boundary = "--" + boundary
  943.       quoted_boundary = Regexp.quote(boundary, "n")
  944.       buf = ""
  945.       bufsize = 10 * 1024
  946.       boundary_end=""
  947.  
  948.       # start multipart/form-data
  949.       stdinput.binmode if defined? stdinput.binmode
  950.       boundary_size = boundary.size + EOL.size
  951.       content_length -= boundary_size
  952.       status = stdinput.read(boundary_size)
  953.       if nil == status
  954.         raise EOFError, "no content body"
  955.       elsif boundary + EOL != status
  956.         raise EOFError, "bad content body"
  957.       end
  958.  
  959.       loop do
  960.         head = nil
  961.         if 10240 < content_length
  962.           require "tempfile"
  963.           body = Tempfile.new("CGI")
  964.         else
  965.           begin
  966.             require "stringio"
  967.             body = StringIO.new
  968.           rescue LoadError
  969.             require "tempfile"
  970.             body = Tempfile.new("CGI")
  971.           end
  972.         end
  973.         body.binmode if defined? body.binmode
  974.  
  975.         until head and /#{quoted_boundary}(?:#{EOL}|--)/n.match(buf)
  976.  
  977.           if (not head) and /#{EOL}#{EOL}/n.match(buf)
  978.             buf = buf.sub(/\A((?:.|\n)*?#{EOL})#{EOL}/n) do
  979.               head = $1.dup
  980.               ""
  981.             end
  982.             next
  983.           end
  984.  
  985.           if head and ( (EOL + boundary + EOL).size < buf.size )
  986.             body.print buf[0 ... (buf.size - (EOL + boundary + EOL).size)]
  987.             buf[0 ... (buf.size - (EOL + boundary + EOL).size)] = ""
  988.           end
  989.  
  990.           c = if bufsize < content_length
  991.                 stdinput.read(bufsize)
  992.               else
  993.                 stdinput.read(content_length)
  994.               end
  995.           if c.nil? || c.empty?
  996.             raise EOFError, "bad content body"
  997.           end
  998.           buf.concat(c)
  999.           content_length -= c.size
  1000.         end
  1001.  
  1002.         buf = buf.sub(/\A((?:.|\n)*?)(?:[\r\n]{1,2})?#{quoted_boundary}([\r\n]{1,2}|--)/n) do
  1003.           body.print $1
  1004.           if "--" == $2
  1005.             content_length = -1
  1006.           end
  1007.           boundary_end = $2.dup
  1008.           ""
  1009.         end
  1010.  
  1011.         body.rewind
  1012.  
  1013.         /Content-Disposition:.* filename=(?:"((?:\\.|[^\"])*)"|([^;\s]*))/ni.match(head)
  1014.     filename = ($1 or $2 or "")
  1015.     if /Mac/ni.match(env_table['HTTP_USER_AGENT']) and
  1016.         /Mozilla/ni.match(env_table['HTTP_USER_AGENT']) and
  1017.         (not /MSIE/ni.match(env_table['HTTP_USER_AGENT']))
  1018.       filename = CGI::unescape(filename)
  1019.     end
  1020.         
  1021.         /Content-Type: ([^\s]*)/ni.match(head)
  1022.         content_type = ($1 or "")
  1023.  
  1024.         (class << body; self; end).class_eval do
  1025.           alias local_path path
  1026.           define_method(:original_filename) {filename.dup.taint}
  1027.           define_method(:content_type) {content_type.dup.taint}
  1028.         end
  1029.  
  1030.         /Content-Disposition:.* name="?([^\";\s]*)"?/ni.match(head)
  1031.         name = $1.dup
  1032.  
  1033.         if params.has_key?(name)
  1034.           params[name].push(body)
  1035.         else
  1036.           params[name] = [body]
  1037.         end
  1038.         break if buf.size == 0
  1039.         break if content_length == -1
  1040.       end
  1041.       raise EOFError, "bad boundary end of body part" unless boundary_end=~/--/
  1042.  
  1043.       params
  1044.     end # read_multipart
  1045.     private :read_multipart
  1046.  
  1047.     # offline mode. read name=value pairs on standard input.
  1048.     def read_from_cmdline
  1049.       require "shellwords"
  1050.  
  1051.       string = unless ARGV.empty?
  1052.         ARGV.join(' ')
  1053.       else
  1054.         if STDIN.tty?
  1055.           STDERR.print(
  1056.             %|(offline mode: enter name=value pairs on standard input)\n|
  1057.           )
  1058.         end
  1059.         array = readlines rescue nil
  1060.         if not array.nil?
  1061.           array.join(' ').gsub(/\n/n, '')
  1062.         else
  1063.           ""
  1064.         end
  1065.       end.gsub(/\\=/n, '%3D').gsub(/\\&/n, '%26')
  1066.  
  1067.       words = Shellwords.shellwords(string)
  1068.  
  1069.       if words.find{|x| /=/n.match(x) }
  1070.         words.join('&')
  1071.       else
  1072.         words.join('+')
  1073.       end
  1074.     end
  1075.     private :read_from_cmdline
  1076.  
  1077.     # Initialize the data from the query.
  1078.     #
  1079.     # Handles multipart forms (in particular, forms that involve file uploads).
  1080.     # Reads query parameters in the @params field, and cookies into @cookies.
  1081.     def initialize_query()
  1082.       if ("POST" == env_table['REQUEST_METHOD']) and
  1083.          %r|\Amultipart/form-data.*boundary=\"?([^\";,]+)\"?|n.match(env_table['CONTENT_TYPE'])
  1084.         boundary = $1.dup
  1085.         @multipart = true
  1086.         @params = read_multipart(boundary, Integer(env_table['CONTENT_LENGTH']))
  1087.       else
  1088.         @multipart = false
  1089.         @params = CGI::parse(
  1090.                     case env_table['REQUEST_METHOD']
  1091.                     when "GET", "HEAD"
  1092.                       if defined?(MOD_RUBY)
  1093.                         Apache::request.args or ""
  1094.                       else
  1095.                         env_table['QUERY_STRING'] or ""
  1096.                       end
  1097.                     when "POST"
  1098.                       stdinput.binmode if defined? stdinput.binmode
  1099.                       stdinput.read(Integer(env_table['CONTENT_LENGTH'])) or ''
  1100.                     else
  1101.                       read_from_cmdline
  1102.                     end
  1103.                   )
  1104.       end
  1105.  
  1106.       @cookies = CGI::Cookie::parse((env_table['HTTP_COOKIE'] or env_table['COOKIE']))
  1107.     end
  1108.     private :initialize_query
  1109.  
  1110.     def multipart?
  1111.       @multipart
  1112.     end
  1113.  
  1114.     module Value    # :nodoc:
  1115.       def set_params(params)
  1116.         @params = params
  1117.       end
  1118.       def [](idx, *args)
  1119.         if args.size == 0
  1120.           warn "#{caller(1)[0]}:CAUTION! cgi['key'] == cgi.params['key'][0]; if want Array, use cgi.params['key']"
  1121.           @params[idx]
  1122.         else
  1123.           super[idx,*args]
  1124.         end
  1125.       end
  1126.       def first
  1127.         warn "#{caller(1)[0]}:CAUTION! cgi['key'] == cgi.params['key'][0]; if want Array, use cgi.params['key']"
  1128.         self
  1129.       end
  1130.       alias last first
  1131.       def to_a
  1132.         @params || [self]
  1133.       end
  1134.       alias to_ary to_a       # to be rhs of multiple assignment
  1135.     end
  1136.  
  1137.     # Get the value for the parameter with a given key.
  1138.     #
  1139.     # If the parameter has multiple values, only the first will be 
  1140.     # retrieved; use #params() to get the array of values.
  1141.     def [](key)
  1142.       params = @params[key]
  1143.       return '' unless params
  1144.       value = params[0]
  1145.       if @multipart
  1146.         if value
  1147.           return value
  1148.         elsif defined? StringIO
  1149.           StringIO.new("")
  1150.         else
  1151.           Tempfile.new("CGI")
  1152.         end
  1153.       else
  1154.         str = if value then value.dup else "" end
  1155.         str.extend(Value)
  1156.         str.set_params(params)
  1157.         str
  1158.       end
  1159.     end
  1160.  
  1161.     # Return all parameter keys as an array.
  1162.     def keys(*args)
  1163.       @params.keys(*args)
  1164.     end
  1165.  
  1166.     # Returns true if a given parameter key exists in the query.
  1167.     def has_key?(*args)
  1168.       @params.has_key?(*args)
  1169.     end
  1170.     alias key? has_key?
  1171.     alias include? has_key?
  1172.  
  1173.   end # QueryExtension
  1174.  
  1175.  
  1176.   # Prettify (indent) an HTML string.
  1177.   #
  1178.   # +string+ is the HTML string to indent.  +shift+ is the indentation
  1179.   # unit to use; it defaults to two spaces.
  1180.   #
  1181.   #   print CGI::pretty("<HTML><BODY></BODY></HTML>")
  1182.   #     # <HTML>
  1183.   #     #   <BODY>
  1184.   #     #   </BODY>
  1185.   #     # </HTML>
  1186.   # 
  1187.   #   print CGI::pretty("<HTML><BODY></BODY></HTML>", "\t")
  1188.   #     # <HTML>
  1189.   #     #         <BODY>
  1190.   #     #         </BODY>
  1191.   #     # </HTML>
  1192.   #
  1193.   def CGI::pretty(string, shift = "  ")
  1194.     lines = string.gsub(/(?!\A)<(?:.|\n)*?>/n, "\n\\0").gsub(/<(?:.|\n)*?>(?!\n)/n, "\\0\n")
  1195.     end_pos = 0
  1196.     while end_pos = lines.index(/^<\/(\w+)/n, end_pos)
  1197.       element = $1.dup
  1198.       start_pos = lines.rindex(/^\s*<#{element}/ni, end_pos)
  1199.       lines[start_pos ... end_pos] = "__" + lines[start_pos ... end_pos].gsub(/\n(?!\z)/n, "\n" + shift) + "__"
  1200.     end
  1201.     lines.gsub(/^((?:#{Regexp::quote(shift)})*)__(?=<\/?\w)/n, '\1')
  1202.   end
  1203.  
  1204.  
  1205.   # Base module for HTML-generation mixins.
  1206.   #
  1207.   # Provides methods for code generation for tags following
  1208.   # the various DTD element types.
  1209.   module TagMaker # :nodoc:
  1210.  
  1211.     # Generate code for an element with required start and end tags.
  1212.     #
  1213.     #   - -
  1214.     def nn_element_def(element)
  1215.       nOE_element_def(element, <<-END)
  1216.           if block_given?
  1217.             yield.to_s
  1218.           else
  1219.             ""
  1220.           end +
  1221.           "</#{element.upcase}>"
  1222.       END
  1223.     end
  1224.  
  1225.     # Generate code for an empty element.
  1226.     #
  1227.     #   - O EMPTY
  1228.     def nOE_element_def(element, append = nil)
  1229.       s = <<-END
  1230.           "<#{element.upcase}" + attributes.collect{|name, value|
  1231.             next unless value
  1232.             " " + CGI::escapeHTML(name) +
  1233.             if true == value
  1234.               ""
  1235.             else
  1236.               '="' + CGI::escapeHTML(value) + '"'
  1237.             end
  1238.           }.to_s + ">"
  1239.       END
  1240.       s.sub!(/\Z/, " +") << append if append
  1241.       s
  1242.     end
  1243.  
  1244.     # Generate code for an element for which the end (and possibly the
  1245.     # start) tag is optional.
  1246.     #
  1247.     #   O O or - O
  1248.     def nO_element_def(element)
  1249.       nOE_element_def(element, <<-END)
  1250.           if block_given?
  1251.             yield.to_s + "</#{element.upcase}>"
  1252.           else
  1253.             ""
  1254.           end
  1255.       END
  1256.     end
  1257.  
  1258.   end # TagMaker
  1259.  
  1260.  
  1261.   #
  1262.   # Mixin module providing HTML generation methods.
  1263.   #
  1264.   # For example,
  1265.   #   cgi.a("http://www.example.com") { "Example" }
  1266.   #     # => "<A HREF=\"http://www.example.com\">Example</A>"
  1267.   #
  1268.   # Modules Http3, Http4, etc., contain more basic HTML-generation methods
  1269.   # (:title, :center, etc.).
  1270.   #
  1271.   # See class CGI for a detailed example. 
  1272.   #
  1273.   module HtmlExtension
  1274.  
  1275.  
  1276.     # Generate an Anchor element as a string.
  1277.     #
  1278.     # +href+ can either be a string, giving the URL
  1279.     # for the HREF attribute, or it can be a hash of
  1280.     # the element's attributes.
  1281.     #
  1282.     # The body of the element is the string returned by the no-argument
  1283.     # block passed in.
  1284.     #
  1285.     #   a("http://www.example.com") { "Example" }
  1286.     #     # => "<A HREF=\"http://www.example.com\">Example</A>"
  1287.     #
  1288.     #   a("HREF" => "http://www.example.com", "TARGET" => "_top") { "Example" }
  1289.     #     # => "<A HREF=\"http://www.example.com\" TARGET=\"_top\">Example</A>"
  1290.     #
  1291.     def a(href = "") # :yield:
  1292.       attributes = if href.kind_of?(String)
  1293.                      { "HREF" => href }
  1294.                    else
  1295.                      href
  1296.                    end
  1297.       if block_given?
  1298.         super(attributes){ yield }
  1299.       else
  1300.         super(attributes)
  1301.       end
  1302.     end
  1303.  
  1304.     # Generate a Document Base URI element as a String. 
  1305.     #
  1306.     # +href+ can either by a string, giving the base URL for the HREF
  1307.     # attribute, or it can be a has of the element's attributes.
  1308.     #
  1309.     # The passed-in no-argument block is ignored.
  1310.     #
  1311.     #   base("http://www.example.com/cgi")
  1312.     #     # => "<BASE HREF=\"http://www.example.com/cgi\">"
  1313.     def base(href = "") # :yield:
  1314.       attributes = if href.kind_of?(String)
  1315.                      { "HREF" => href }
  1316.                    else
  1317.                      href
  1318.                    end
  1319.       if block_given?
  1320.         super(attributes){ yield }
  1321.       else
  1322.         super(attributes)
  1323.       end
  1324.     end
  1325.  
  1326.     # Generate a BlockQuote element as a string.
  1327.     #
  1328.     # +cite+ can either be a string, give the URI for the source of
  1329.     # the quoted text, or a hash, giving all attributes of the element,
  1330.     # or it can be omitted, in which case the element has no attributes.
  1331.     #
  1332.     # The body is provided by the passed-in no-argument block
  1333.     #
  1334.     #   blockquote("http://www.example.com/quotes/foo.html") { "Foo!" }
  1335.     #     #=> "<BLOCKQUOTE CITE=\"http://www.example.com/quotes/foo.html\">Foo!</BLOCKQUOTE>
  1336.     def blockquote(cite = nil)  # :yield:
  1337.       attributes = if cite.kind_of?(String)
  1338.                      { "CITE" => cite }
  1339.                    else
  1340.                      cite or ""
  1341.                    end
  1342.       if block_given?
  1343.         super(attributes){ yield }
  1344.       else
  1345.         super(attributes)
  1346.       end
  1347.     end
  1348.  
  1349.  
  1350.     # Generate a Table Caption element as a string.
  1351.     #
  1352.     # +align+ can be a string, giving the alignment of the caption
  1353.     # (one of top, bottom, left, or right).  It can be a hash of
  1354.     # all the attributes of the element.  Or it can be omitted.
  1355.     #
  1356.     # The body of the element is provided by the passed-in no-argument block.
  1357.     #
  1358.     #   caption("left") { "Capital Cities" }
  1359.     #     # => <CAPTION ALIGN=\"left\">Capital Cities</CAPTION>
  1360.     def caption(align = nil) # :yield:
  1361.       attributes = if align.kind_of?(String)
  1362.                      { "ALIGN" => align }
  1363.                    else
  1364.                      align or ""
  1365.                    end
  1366.       if block_given?
  1367.         super(attributes){ yield }
  1368.       else
  1369.         super(attributes)
  1370.       end
  1371.     end
  1372.  
  1373.  
  1374.     # Generate a Checkbox Input element as a string.
  1375.     #
  1376.     # The attributes of the element can be specified as three arguments,
  1377.     # +name+, +value+, and +checked+.  +checked+ is a boolean value;
  1378.     # if true, the CHECKED attribute will be included in the element.
  1379.     #
  1380.     # Alternatively, the attributes can be specified as a hash.
  1381.     #
  1382.     #   checkbox("name")
  1383.     #     # = checkbox("NAME" => "name")
  1384.     # 
  1385.     #   checkbox("name", "value")
  1386.     #     # = checkbox("NAME" => "name", "VALUE" => "value")
  1387.     # 
  1388.     #   checkbox("name", "value", true)
  1389.     #     # = checkbox("NAME" => "name", "VALUE" => "value", "CHECKED" => true)
  1390.     def checkbox(name = "", value = nil, checked = nil)
  1391.       attributes = if name.kind_of?(String)
  1392.                      { "TYPE" => "checkbox", "NAME" => name,
  1393.                        "VALUE" => value, "CHECKED" => checked }
  1394.                    else
  1395.                      name["TYPE"] = "checkbox"
  1396.                      name
  1397.                    end
  1398.       input(attributes)
  1399.     end
  1400.  
  1401.     # Generate a sequence of checkbox elements, as a String.
  1402.     #
  1403.     # The checkboxes will all have the same +name+ attribute.
  1404.     # Each checkbox is followed by a label.
  1405.     # There will be one checkbox for each value.  Each value
  1406.     # can be specified as a String, which will be used both
  1407.     # as the value of the VALUE attribute and as the label
  1408.     # for that checkbox.  A single-element array has the
  1409.     # same effect.
  1410.     #
  1411.     # Each value can also be specified as a three-element array.
  1412.     # The first element is the VALUE attribute; the second is the
  1413.     # label; and the third is a boolean specifying whether this
  1414.     # checkbox is CHECKED.
  1415.     #
  1416.     # Each value can also be specified as a two-element
  1417.     # array, by omitting either the value element (defaults
  1418.     # to the same as the label), or the boolean checked element
  1419.     # (defaults to false).
  1420.     #
  1421.     #   checkbox_group("name", "foo", "bar", "baz")
  1422.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  1423.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="bar">bar
  1424.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz
  1425.     # 
  1426.     #   checkbox_group("name", ["foo"], ["bar", true], "baz")
  1427.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="foo">foo
  1428.     #     # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="bar">bar
  1429.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="baz">baz
  1430.     # 
  1431.     #   checkbox_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1432.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="1">Foo
  1433.     #     # <INPUT TYPE="checkbox" CHECKED NAME="name" VALUE="2">Bar
  1434.     #     # <INPUT TYPE="checkbox" NAME="name" VALUE="Baz">Baz
  1435.     # 
  1436.     #   checkbox_group("NAME" => "name",
  1437.     #                    "VALUES" => ["foo", "bar", "baz"])
  1438.     # 
  1439.     #   checkbox_group("NAME" => "name",
  1440.     #                    "VALUES" => [["foo"], ["bar", true], "baz"])
  1441.     # 
  1442.     #   checkbox_group("NAME" => "name",
  1443.     #                    "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1444.     def checkbox_group(name = "", *values)
  1445.       if name.kind_of?(Hash)
  1446.         values = name["VALUES"]
  1447.         name = name["NAME"]
  1448.       end
  1449.       values.collect{|value|
  1450.         if value.kind_of?(String)
  1451.           checkbox(name, value) + value
  1452.         else
  1453.           if value[value.size - 1] == true
  1454.             checkbox(name, value[0], true) +
  1455.             value[value.size - 2]
  1456.           else
  1457.             checkbox(name, value[0]) +
  1458.             value[value.size - 1]
  1459.           end
  1460.         end
  1461.       }.to_s
  1462.     end
  1463.  
  1464.  
  1465.     # Generate an File Upload Input element as a string.
  1466.     #
  1467.     # The attributes of the element can be specified as three arguments,
  1468.     # +name+, +size+, and +maxlength+.  +maxlength+ is the maximum length
  1469.     # of the file's _name_, not of the file's _contents_.
  1470.     #
  1471.     # Alternatively, the attributes can be specified as a hash.
  1472.     #
  1473.     # See #multipart_form() for forms that include file uploads.
  1474.     #
  1475.     #   file_field("name")
  1476.     #     # <INPUT TYPE="file" NAME="name" SIZE="20">
  1477.     # 
  1478.     #   file_field("name", 40)
  1479.     #     # <INPUT TYPE="file" NAME="name" SIZE="40">
  1480.     # 
  1481.     #   file_field("name", 40, 100)
  1482.     #     # <INPUT TYPE="file" NAME="name" SIZE="40" MAXLENGTH="100">
  1483.     # 
  1484.     #   file_field("NAME" => "name", "SIZE" => 40)
  1485.     #     # <INPUT TYPE="file" NAME="name" SIZE="40">
  1486.     def file_field(name = "", size = 20, maxlength = nil)
  1487.       attributes = if name.kind_of?(String)
  1488.                      { "TYPE" => "file", "NAME" => name,
  1489.                        "SIZE" => size.to_s }
  1490.                    else
  1491.                      name["TYPE"] = "file"
  1492.                      name
  1493.                    end
  1494.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  1495.       input(attributes)
  1496.     end
  1497.  
  1498.  
  1499.     # Generate a Form element as a string.
  1500.     #
  1501.     # +method+ should be either "get" or "post", and defaults to the latter.
  1502.     # +action+ defaults to the current CGI script name.  +enctype+
  1503.     # defaults to "application/x-www-form-urlencoded".  
  1504.     #
  1505.     # Alternatively, the attributes can be specified as a hash.
  1506.     #
  1507.     # See also #multipart_form() for forms that include file uploads.
  1508.     #
  1509.     #   form{ "string" }
  1510.     #     # <FORM METHOD="post" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1511.     # 
  1512.     #   form("get") { "string" }
  1513.     #     # <FORM METHOD="get" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1514.     # 
  1515.     #   form("get", "url") { "string" }
  1516.     #     # <FORM METHOD="get" ACTION="url" ENCTYPE="application/x-www-form-urlencoded">string</FORM>
  1517.     # 
  1518.     #   form("METHOD" => "post", "ENCTYPE" => "enctype") { "string" }
  1519.     #     # <FORM METHOD="post" ENCTYPE="enctype">string</FORM>
  1520.     def form(method = "post", action = script_name, enctype = "application/x-www-form-urlencoded")
  1521.       attributes = if method.kind_of?(String)
  1522.                      { "METHOD" => method, "ACTION" => action,
  1523.                        "ENCTYPE" => enctype } 
  1524.                    else
  1525.                      unless method.has_key?("METHOD")
  1526.                        method["METHOD"] = "post"
  1527.                      end
  1528.                      unless method.has_key?("ENCTYPE")
  1529.                        method["ENCTYPE"] = enctype
  1530.                      end
  1531.                      method
  1532.                    end
  1533.       if block_given?
  1534.         body = yield
  1535.       else
  1536.         body = ""
  1537.       end
  1538.       if @output_hidden
  1539.         body += @output_hidden.collect{|k,v|
  1540.           "<INPUT TYPE=\"HIDDEN\" NAME=\"#{k}\" VALUE=\"#{v}\">"
  1541.         }.to_s
  1542.       end
  1543.       super(attributes){body}
  1544.     end
  1545.  
  1546.     # Generate a Hidden Input element as a string.
  1547.     #
  1548.     # The attributes of the element can be specified as two arguments,
  1549.     # +name+ and +value+.
  1550.     #
  1551.     # Alternatively, the attributes can be specified as a hash.
  1552.     #
  1553.     #   hidden("name")
  1554.     #     # <INPUT TYPE="hidden" NAME="name">
  1555.     # 
  1556.     #   hidden("name", "value")
  1557.     #     # <INPUT TYPE="hidden" NAME="name" VALUE="value">
  1558.     # 
  1559.     #   hidden("NAME" => "name", "VALUE" => "reset", "ID" => "foo")
  1560.     #     # <INPUT TYPE="hidden" NAME="name" VALUE="value" ID="foo">
  1561.     def hidden(name = "", value = nil)
  1562.       attributes = if name.kind_of?(String)
  1563.                      { "TYPE" => "hidden", "NAME" => name, "VALUE" => value }
  1564.                    else
  1565.                      name["TYPE"] = "hidden"
  1566.                      name
  1567.                    end
  1568.       input(attributes)
  1569.     end
  1570.  
  1571.     # Generate a top-level HTML element as a string.
  1572.     #
  1573.     # The attributes of the element are specified as a hash.  The
  1574.     # pseudo-attribute "PRETTY" can be used to specify that the generated
  1575.     # HTML string should be indented.  "PRETTY" can also be specified as
  1576.     # a string as the sole argument to this method.  The pseudo-attribute
  1577.     # "DOCTYPE", if given, is used as the leading DOCTYPE SGML tag; it
  1578.     # should include the entire text of this tag, including angle brackets.
  1579.     #
  1580.     # The body of the html element is supplied as a block.
  1581.     # 
  1582.     #   html{ "string" }
  1583.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML>string</HTML>
  1584.     # 
  1585.     #   html("LANG" => "ja") { "string" }
  1586.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"><HTML LANG="ja">string</HTML>
  1587.     # 
  1588.     #   html("DOCTYPE" => false) { "string" }
  1589.     #     # <HTML>string</HTML>
  1590.     # 
  1591.     #   html("DOCTYPE" => '<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">') { "string" }
  1592.     #     # <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"><HTML>string</HTML>
  1593.     # 
  1594.     #   html("PRETTY" => "  ") { "<BODY></BODY>" }
  1595.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  1596.     #     # <HTML>
  1597.     #     #   <BODY>
  1598.     #     #   </BODY>
  1599.     #     # </HTML>
  1600.     # 
  1601.     #   html("PRETTY" => "\t") { "<BODY></BODY>" }
  1602.     #     # <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
  1603.     #     # <HTML>
  1604.     #     #         <BODY>
  1605.     #     #         </BODY>
  1606.     #     # </HTML>
  1607.     # 
  1608.     #   html("PRETTY") { "<BODY></BODY>" }
  1609.     #     # = html("PRETTY" => "  ") { "<BODY></BODY>" }
  1610.     # 
  1611.     #   html(if $VERBOSE then "PRETTY" end) { "HTML string" }
  1612.     #
  1613.     def html(attributes = {}) # :yield:
  1614.       if nil == attributes
  1615.         attributes = {}
  1616.       elsif "PRETTY" == attributes
  1617.         attributes = { "PRETTY" => true }
  1618.       end
  1619.       pretty = attributes.delete("PRETTY")
  1620.       pretty = "  " if true == pretty
  1621.       buf = ""
  1622.  
  1623.       if attributes.has_key?("DOCTYPE")
  1624.         if attributes["DOCTYPE"]
  1625.           buf += attributes.delete("DOCTYPE")
  1626.         else
  1627.           attributes.delete("DOCTYPE")
  1628.         end
  1629.       else
  1630.         buf += doctype
  1631.       end
  1632.  
  1633.       if block_given?
  1634.         buf += super(attributes){ yield }
  1635.       else
  1636.         buf += super(attributes)
  1637.       end
  1638.  
  1639.       if pretty
  1640.         CGI::pretty(buf, pretty)
  1641.       else
  1642.         buf
  1643.       end
  1644.  
  1645.     end
  1646.  
  1647.     # Generate an Image Button Input element as a string.
  1648.     #
  1649.     # +src+ is the URL of the image to use for the button.  +name+ 
  1650.     # is the input name.  +alt+ is the alternative text for the image.
  1651.     #
  1652.     # Alternatively, the attributes can be specified as a hash.
  1653.     # 
  1654.     #   image_button("url")
  1655.     #     # <INPUT TYPE="image" SRC="url">
  1656.     # 
  1657.     #   image_button("url", "name", "string")
  1658.     #     # <INPUT TYPE="image" SRC="url" NAME="name" ALT="string">
  1659.     # 
  1660.     #   image_button("SRC" => "url", "ATL" => "strng")
  1661.     #     # <INPUT TYPE="image" SRC="url" ALT="string">
  1662.     def image_button(src = "", name = nil, alt = nil)
  1663.       attributes = if src.kind_of?(String)
  1664.                      { "TYPE" => "image", "SRC" => src, "NAME" => name,
  1665.                        "ALT" => alt }
  1666.                    else
  1667.                      src["TYPE"] = "image"
  1668.                      src["SRC"] ||= ""
  1669.                      src
  1670.                    end
  1671.       input(attributes)
  1672.     end
  1673.  
  1674.  
  1675.     # Generate an Image element as a string.
  1676.     #
  1677.     # +src+ is the URL of the image.  +alt+ is the alternative text for
  1678.     # the image.  +width+ is the width of the image, and +height+ is
  1679.     # its height.
  1680.     #
  1681.     # Alternatively, the attributes can be specified as a hash.
  1682.     #
  1683.     #   img("src", "alt", 100, 50)
  1684.     #     # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">
  1685.     # 
  1686.     #   img("SRC" => "src", "ALT" => "alt", "WIDTH" => 100, "HEIGHT" => 50)
  1687.     #     # <IMG SRC="src" ALT="alt" WIDTH="100" HEIGHT="50">
  1688.     def img(src = "", alt = "", width = nil, height = nil)
  1689.       attributes = if src.kind_of?(String)
  1690.                      { "SRC" => src, "ALT" => alt }
  1691.                    else
  1692.                      src
  1693.                    end
  1694.       attributes["WIDTH"] = width.to_s if width
  1695.       attributes["HEIGHT"] = height.to_s if height
  1696.       super(attributes)
  1697.     end
  1698.  
  1699.  
  1700.     # Generate a Form element with multipart encoding as a String.
  1701.     #
  1702.     # Multipart encoding is used for forms that include file uploads.
  1703.     #
  1704.     # +action+ is the action to perform.  +enctype+ is the encoding
  1705.     # type, which defaults to "multipart/form-data".
  1706.     #
  1707.     # Alternatively, the attributes can be specified as a hash.
  1708.     #
  1709.     #   multipart_form{ "string" }
  1710.     #     # <FORM METHOD="post" ENCTYPE="multipart/form-data">string</FORM>
  1711.     # 
  1712.     #   multipart_form("url") { "string" }
  1713.     #     # <FORM METHOD="post" ACTION="url" ENCTYPE="multipart/form-data">string</FORM>
  1714.     def multipart_form(action = nil, enctype = "multipart/form-data")
  1715.       attributes = if action == nil
  1716.                      { "METHOD" => "post", "ENCTYPE" => enctype } 
  1717.                    elsif action.kind_of?(String)
  1718.                      { "METHOD" => "post", "ACTION" => action,
  1719.                        "ENCTYPE" => enctype } 
  1720.                    else
  1721.                      unless action.has_key?("METHOD")
  1722.                        action["METHOD"] = "post"
  1723.                      end
  1724.                      unless action.has_key?("ENCTYPE")
  1725.                        action["ENCTYPE"] = enctype
  1726.                      end
  1727.                      action
  1728.                    end
  1729.       if block_given?
  1730.         form(attributes){ yield }
  1731.       else
  1732.         form(attributes)
  1733.       end
  1734.     end
  1735.  
  1736.  
  1737.     # Generate a Password Input element as a string.
  1738.     #
  1739.     # +name+ is the name of the input field.  +value+ is its default
  1740.     # value.  +size+ is the size of the input field display.  +maxlength+
  1741.     # is the maximum length of the inputted password.
  1742.     #
  1743.     # Alternatively, attributes can be specified as a hash.
  1744.     #
  1745.     #   password_field("name")
  1746.     #     # <INPUT TYPE="password" NAME="name" SIZE="40">
  1747.     # 
  1748.     #   password_field("name", "value")
  1749.     #     # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="40">
  1750.     # 
  1751.     #   password_field("password", "value", 80, 200)
  1752.     #     # <INPUT TYPE="password" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">
  1753.     # 
  1754.     #   password_field("NAME" => "name", "VALUE" => "value")
  1755.     #     # <INPUT TYPE="password" NAME="name" VALUE="value">
  1756.     def password_field(name = "", value = nil, size = 40, maxlength = nil)
  1757.       attributes = if name.kind_of?(String)
  1758.                      { "TYPE" => "password", "NAME" => name,
  1759.                        "VALUE" => value, "SIZE" => size.to_s }
  1760.                    else
  1761.                      name["TYPE"] = "password"
  1762.                      name
  1763.                    end
  1764.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  1765.       input(attributes)
  1766.     end
  1767.  
  1768.     # Generate a Select element as a string.
  1769.     #
  1770.     # +name+ is the name of the element.  The +values+ are the options that
  1771.     # can be selected from the Select menu.  Each value can be a String or
  1772.     # a one, two, or three-element Array.  If a String or a one-element
  1773.     # Array, this is both the value of that option and the text displayed for
  1774.     # it.  If a three-element Array, the elements are the option value, displayed
  1775.     # text, and a boolean value specifying whether this option starts as selected.
  1776.     # The two-element version omits either the option value (defaults to the same
  1777.     # as the display text) or the boolean selected specifier (defaults to false).
  1778.     #
  1779.     # The attributes and options can also be specified as a hash.  In this
  1780.     # case, options are specified as an array of values as described above,
  1781.     # with the hash key of "VALUES".
  1782.     #
  1783.     #   popup_menu("name", "foo", "bar", "baz")
  1784.     #     # <SELECT NAME="name">
  1785.     #     #   <OPTION VALUE="foo">foo</OPTION>
  1786.     #     #   <OPTION VALUE="bar">bar</OPTION>
  1787.     #     #   <OPTION VALUE="baz">baz</OPTION>
  1788.     #     # </SELECT>
  1789.     # 
  1790.     #   popup_menu("name", ["foo"], ["bar", true], "baz")
  1791.     #     # <SELECT NAME="name">
  1792.     #     #   <OPTION VALUE="foo">foo</OPTION>
  1793.     #     #   <OPTION VALUE="bar" SELECTED>bar</OPTION>
  1794.     #     #   <OPTION VALUE="baz">baz</OPTION>
  1795.     #     # </SELECT>
  1796.     # 
  1797.     #   popup_menu("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1798.     #     # <SELECT NAME="name">
  1799.     #     #   <OPTION VALUE="1">Foo</OPTION>
  1800.     #     #   <OPTION SELECTED VALUE="2">Bar</OPTION>
  1801.     #     #   <OPTION VALUE="Baz">Baz</OPTION>
  1802.     #     # </SELECT>
  1803.     # 
  1804.     #   popup_menu("NAME" => "name", "SIZE" => 2, "MULTIPLE" => true,
  1805.     #               "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1806.     #     # <SELECT NAME="name" MULTIPLE SIZE="2">
  1807.     #     #   <OPTION VALUE="1">Foo</OPTION>
  1808.     #     #   <OPTION SELECTED VALUE="2">Bar</OPTION>
  1809.     #     #   <OPTION VALUE="Baz">Baz</OPTION>
  1810.     #     # </SELECT>
  1811.     def popup_menu(name = "", *values)
  1812.  
  1813.       if name.kind_of?(Hash)
  1814.         values   = name["VALUES"]
  1815.         size     = name["SIZE"].to_s if name["SIZE"]
  1816.         multiple = name["MULTIPLE"]
  1817.         name     = name["NAME"]
  1818.       else
  1819.         size = nil
  1820.         multiple = nil
  1821.       end
  1822.  
  1823.       select({ "NAME" => name, "SIZE" => size,
  1824.                "MULTIPLE" => multiple }){
  1825.         values.collect{|value|
  1826.           if value.kind_of?(String)
  1827.             option({ "VALUE" => value }){ value }
  1828.           else
  1829.             if value[value.size - 1] == true
  1830.               option({ "VALUE" => value[0], "SELECTED" => true }){
  1831.                 value[value.size - 2]
  1832.               }
  1833.             else
  1834.               option({ "VALUE" => value[0] }){
  1835.                 value[value.size - 1]
  1836.               }
  1837.             end
  1838.           end
  1839.         }.to_s
  1840.       }
  1841.  
  1842.     end
  1843.  
  1844.     # Generates a radio-button Input element.
  1845.     #
  1846.     # +name+ is the name of the input field.  +value+ is the value of
  1847.     # the field if checked.  +checked+ specifies whether the field
  1848.     # starts off checked.
  1849.     #
  1850.     # Alternatively, the attributes can be specified as a hash.
  1851.     #
  1852.     #   radio_button("name", "value")
  1853.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value">
  1854.     # 
  1855.     #   radio_button("name", "value", true)
  1856.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value" CHECKED>
  1857.     # 
  1858.     #   radio_button("NAME" => "name", "VALUE" => "value", "ID" => "foo")
  1859.     #     # <INPUT TYPE="radio" NAME="name" VALUE="value" ID="foo">
  1860.     def radio_button(name = "", value = nil, checked = nil)
  1861.       attributes = if name.kind_of?(String)
  1862.                      { "TYPE" => "radio", "NAME" => name,
  1863.                        "VALUE" => value, "CHECKED" => checked }
  1864.                    else
  1865.                      name["TYPE"] = "radio"
  1866.                      name
  1867.                    end
  1868.       input(attributes)
  1869.     end
  1870.  
  1871.     # Generate a sequence of radio button Input elements, as a String.
  1872.     #
  1873.     # This works the same as #checkbox_group().  However, it is not valid
  1874.     # to have more than one radiobutton in a group checked.
  1875.     # 
  1876.     #   radio_group("name", "foo", "bar", "baz")
  1877.     #     # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  1878.     #     # <INPUT TYPE="radio" NAME="name" VALUE="bar">bar
  1879.     #     # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz
  1880.     # 
  1881.     #   radio_group("name", ["foo"], ["bar", true], "baz")
  1882.     #     # <INPUT TYPE="radio" NAME="name" VALUE="foo">foo
  1883.     #     # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="bar">bar
  1884.     #     # <INPUT TYPE="radio" NAME="name" VALUE="baz">baz
  1885.     # 
  1886.     #   radio_group("name", ["1", "Foo"], ["2", "Bar", true], "Baz")
  1887.     #     # <INPUT TYPE="radio" NAME="name" VALUE="1">Foo
  1888.     #     # <INPUT TYPE="radio" CHECKED NAME="name" VALUE="2">Bar
  1889.     #     # <INPUT TYPE="radio" NAME="name" VALUE="Baz">Baz
  1890.     # 
  1891.     #   radio_group("NAME" => "name",
  1892.     #                 "VALUES" => ["foo", "bar", "baz"])
  1893.     # 
  1894.     #   radio_group("NAME" => "name",
  1895.     #                 "VALUES" => [["foo"], ["bar", true], "baz"])
  1896.     # 
  1897.     #   radio_group("NAME" => "name",
  1898.     #                 "VALUES" => [["1", "Foo"], ["2", "Bar", true], "Baz"])
  1899.     def radio_group(name = "", *values)
  1900.       if name.kind_of?(Hash)
  1901.         values = name["VALUES"]
  1902.         name = name["NAME"]
  1903.       end
  1904.       values.collect{|value|
  1905.         if value.kind_of?(String)
  1906.           radio_button(name, value) + value
  1907.         else
  1908.           if value[value.size - 1] == true
  1909.             radio_button(name, value[0], true) +
  1910.             value[value.size - 2]
  1911.           else
  1912.             radio_button(name, value[0]) +
  1913.             value[value.size - 1]
  1914.           end
  1915.         end
  1916.       }.to_s
  1917.     end
  1918.  
  1919.     # Generate a reset button Input element, as a String.
  1920.     #
  1921.     # This resets the values on a form to their initial values.  +value+
  1922.     # is the text displayed on the button. +name+ is the name of this button.
  1923.     #
  1924.     # Alternatively, the attributes can be specified as a hash.
  1925.     #
  1926.     #   reset
  1927.     #     # <INPUT TYPE="reset">
  1928.     # 
  1929.     #   reset("reset")
  1930.     #     # <INPUT TYPE="reset" VALUE="reset">
  1931.     # 
  1932.     #   reset("VALUE" => "reset", "ID" => "foo")
  1933.     #     # <INPUT TYPE="reset" VALUE="reset" ID="foo">
  1934.     def reset(value = nil, name = nil)
  1935.       attributes = if (not value) or value.kind_of?(String)
  1936.                      { "TYPE" => "reset", "VALUE" => value, "NAME" => name }
  1937.                    else
  1938.                      value["TYPE"] = "reset"
  1939.                      value
  1940.                    end
  1941.       input(attributes)
  1942.     end
  1943.  
  1944.     alias scrolling_list popup_menu
  1945.  
  1946.     # Generate a submit button Input element, as a String.
  1947.     #
  1948.     # +value+ is the text to display on the button.  +name+ is the name
  1949.     # of the input.
  1950.     #
  1951.     # Alternatively, the attributes can be specified as a hash.
  1952.     #
  1953.     #   submit
  1954.     #     # <INPUT TYPE="submit">
  1955.     # 
  1956.     #   submit("ok")
  1957.     #     # <INPUT TYPE="submit" VALUE="ok">
  1958.     # 
  1959.     #   submit("ok", "button1")
  1960.     #     # <INPUT TYPE="submit" VALUE="ok" NAME="button1">
  1961.     # 
  1962.     #   submit("VALUE" => "ok", "NAME" => "button1", "ID" => "foo")
  1963.     #     # <INPUT TYPE="submit" VALUE="ok" NAME="button1" ID="foo">
  1964.     def submit(value = nil, name = nil)
  1965.       attributes = if (not value) or value.kind_of?(String)
  1966.                      { "TYPE" => "submit", "VALUE" => value, "NAME" => name }
  1967.                    else
  1968.                      value["TYPE"] = "submit"
  1969.                      value
  1970.                    end
  1971.       input(attributes)
  1972.     end
  1973.  
  1974.     # Generate a text field Input element, as a String.
  1975.     #
  1976.     # +name+ is the name of the input field.  +value+ is its initial
  1977.     # value.  +size+ is the size of the input area.  +maxlength+
  1978.     # is the maximum length of input accepted.
  1979.     #
  1980.     # Alternatively, the attributes can be specified as a hash.
  1981.     #
  1982.     #   text_field("name")
  1983.     #     # <INPUT TYPE="text" NAME="name" SIZE="40">
  1984.     # 
  1985.     #   text_field("name", "value")
  1986.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="40">
  1987.     # 
  1988.     #   text_field("name", "value", 80)
  1989.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80">
  1990.     # 
  1991.     #   text_field("name", "value", 80, 200)
  1992.     #     # <INPUT TYPE="text" NAME="name" VALUE="value" SIZE="80" MAXLENGTH="200">
  1993.     # 
  1994.     #   text_field("NAME" => "name", "VALUE" => "value")
  1995.     #     # <INPUT TYPE="text" NAME="name" VALUE="value">
  1996.     def text_field(name = "", value = nil, size = 40, maxlength = nil)
  1997.       attributes = if name.kind_of?(String)
  1998.                      { "TYPE" => "text", "NAME" => name, "VALUE" => value,
  1999.                        "SIZE" => size.to_s }
  2000.                    else
  2001.                      name["TYPE"] = "text"
  2002.                      name
  2003.                    end
  2004.       attributes["MAXLENGTH"] = maxlength.to_s if maxlength
  2005.       input(attributes)
  2006.     end
  2007.  
  2008.     # Generate a TextArea element, as a String.
  2009.     #
  2010.     # +name+ is the name of the textarea.  +cols+ is the number of
  2011.     # columns and +rows+ is the number of rows in the display.
  2012.     #
  2013.     # Alternatively, the attributes can be specified as a hash.
  2014.     #
  2015.     # The body is provided by the passed-in no-argument block
  2016.     #
  2017.     #   textarea("name")
  2018.     #      # = textarea("NAME" => "name", "COLS" => 70, "ROWS" => 10)
  2019.     #
  2020.     #   textarea("name", 40, 5)
  2021.     #      # = textarea("NAME" => "name", "COLS" => 40, "ROWS" => 5)
  2022.     def textarea(name = "", cols = 70, rows = 10)  # :yield:
  2023.       attributes = if name.kind_of?(String)
  2024.                      { "NAME" => name, "COLS" => cols.to_s,
  2025.                        "ROWS" => rows.to_s }
  2026.                    else
  2027.                      name
  2028.                    end
  2029.       if block_given?
  2030.         super(attributes){ yield }
  2031.       else
  2032.         super(attributes)
  2033.       end
  2034.     end
  2035.  
  2036.   end # HtmlExtension
  2037.  
  2038.  
  2039.   # Mixin module for HTML version 3 generation methods.
  2040.   module Html3 # :nodoc:
  2041.  
  2042.     # The DOCTYPE declaration for this version of HTML
  2043.     def doctype
  2044.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">|
  2045.     end
  2046.  
  2047.     # Initialise the HTML generation methods for this version.
  2048.     def element_init
  2049.       extend TagMaker
  2050.       methods = ""
  2051.       # - -
  2052.       for element in %w[ A TT I B U STRIKE BIG SMALL SUB SUP EM STRONG
  2053.           DFN CODE SAMP KBD VAR CITE FONT ADDRESS DIV center MAP
  2054.           APPLET PRE XMP LISTING DL OL UL DIR MENU SELECT table TITLE
  2055.           STYLE SCRIPT H1 H2 H3 H4 H5 H6 TEXTAREA FORM BLOCKQUOTE
  2056.           CAPTION ]
  2057.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2058.           def #{element.downcase}(attributes = {})
  2059.         BEGIN
  2060.           end
  2061.         END
  2062.       end
  2063.  
  2064.       # - O EMPTY
  2065.       for element in %w[ IMG BASE BASEFONT BR AREA LINK PARAM HR INPUT
  2066.           ISINDEX META ]
  2067.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2068.           def #{element.downcase}(attributes = {})
  2069.         BEGIN
  2070.           end
  2071.         END
  2072.       end
  2073.  
  2074.       # O O or - O
  2075.       for element in %w[ HTML HEAD BODY P PLAINTEXT DT DD LI OPTION tr
  2076.           th td ]
  2077.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2078.           def #{element.downcase}(attributes = {})
  2079.         BEGIN
  2080.           end
  2081.         END
  2082.       end
  2083.       eval(methods)
  2084.     end
  2085.  
  2086.   end # Html3
  2087.  
  2088.  
  2089.   # Mixin module for HTML version 4 generation methods.
  2090.   module Html4 # :nodoc:
  2091.  
  2092.     # The DOCTYPE declaration for this version of HTML
  2093.     def doctype
  2094.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">|
  2095.     end
  2096.  
  2097.     # Initialise the HTML generation methods for this version.
  2098.     def element_init
  2099.       extend TagMaker
  2100.       methods = ""
  2101.       # - -
  2102.       for element in %w[ TT I B BIG SMALL EM STRONG DFN CODE SAMP KBD
  2103.         VAR CITE ABBR ACRONYM SUB SUP SPAN BDO ADDRESS DIV MAP OBJECT
  2104.         H1 H2 H3 H4 H5 H6 PRE Q INS DEL DL OL UL LABEL SELECT OPTGROUP
  2105.         FIELDSET LEGEND BUTTON TABLE TITLE STYLE SCRIPT NOSCRIPT
  2106.         TEXTAREA FORM A BLOCKQUOTE CAPTION ]
  2107.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2108.           def #{element.downcase}(attributes = {})
  2109.         BEGIN
  2110.           end
  2111.         END
  2112.       end
  2113.  
  2114.       # - O EMPTY
  2115.       for element in %w[ IMG BASE BR AREA LINK PARAM HR INPUT COL META ]
  2116.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2117.           def #{element.downcase}(attributes = {})
  2118.         BEGIN
  2119.           end
  2120.         END
  2121.       end
  2122.  
  2123.       # O O or - O
  2124.       for element in %w[ HTML BODY P DT DD LI OPTION THEAD TFOOT TBODY
  2125.           COLGROUP TR TH TD HEAD]
  2126.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2127.           def #{element.downcase}(attributes = {})
  2128.         BEGIN
  2129.           end
  2130.         END
  2131.       end
  2132.       eval(methods)
  2133.     end
  2134.  
  2135.   end # Html4
  2136.  
  2137.  
  2138.   # Mixin module for HTML version 4 transitional generation methods.
  2139.   module Html4Tr # :nodoc:
  2140.  
  2141.     # The DOCTYPE declaration for this version of HTML
  2142.     def doctype
  2143.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">|
  2144.     end
  2145.  
  2146.     # Initialise the HTML generation methods for this version.
  2147.     def element_init
  2148.       extend TagMaker
  2149.       methods = ""
  2150.       # - -
  2151.       for element in %w[ TT I B U S STRIKE BIG SMALL EM STRONG DFN
  2152.           CODE SAMP KBD VAR CITE ABBR ACRONYM FONT SUB SUP SPAN BDO
  2153.           ADDRESS DIV CENTER MAP OBJECT APPLET H1 H2 H3 H4 H5 H6 PRE Q
  2154.           INS DEL DL OL UL DIR MENU LABEL SELECT OPTGROUP FIELDSET
  2155.           LEGEND BUTTON TABLE IFRAME NOFRAMES TITLE STYLE SCRIPT
  2156.           NOSCRIPT TEXTAREA FORM A BLOCKQUOTE CAPTION ]
  2157.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2158.           def #{element.downcase}(attributes = {})
  2159.         BEGIN
  2160.           end
  2161.         END
  2162.       end
  2163.  
  2164.       # - O EMPTY
  2165.       for element in %w[ IMG BASE BASEFONT BR AREA LINK PARAM HR INPUT
  2166.           COL ISINDEX META ]
  2167.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2168.           def #{element.downcase}(attributes = {})
  2169.         BEGIN
  2170.           end
  2171.         END
  2172.       end
  2173.  
  2174.       # O O or - O
  2175.       for element in %w[ HTML BODY P DT DD LI OPTION THEAD TFOOT TBODY
  2176.           COLGROUP TR TH TD HEAD ]
  2177.         methods += <<-BEGIN + nO_element_def(element) + <<-END
  2178.           def #{element.downcase}(attributes = {})
  2179.         BEGIN
  2180.           end
  2181.         END
  2182.       end
  2183.       eval(methods)
  2184.     end
  2185.  
  2186.   end # Html4Tr
  2187.  
  2188.  
  2189.   # Mixin module for generating HTML version 4 with framesets.
  2190.   module Html4Fr # :nodoc:
  2191.  
  2192.     # The DOCTYPE declaration for this version of HTML
  2193.     def doctype
  2194.       %|<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN" "http://www.w3.org/TR/html4/frameset.dtd">|
  2195.     end
  2196.  
  2197.     # Initialise the HTML generation methods for this version.
  2198.     def element_init
  2199.       methods = ""
  2200.       # - -
  2201.       for element in %w[ FRAMESET ]
  2202.         methods += <<-BEGIN + nn_element_def(element) + <<-END
  2203.           def #{element.downcase}(attributes = {})
  2204.         BEGIN
  2205.           end
  2206.         END
  2207.       end
  2208.  
  2209.       # - O EMPTY
  2210.       for element in %w[ FRAME ]
  2211.         methods += <<-BEGIN + nOE_element_def(element) + <<-END
  2212.           def #{element.downcase}(attributes = {})
  2213.         BEGIN
  2214.           end
  2215.         END
  2216.       end
  2217.       eval(methods)
  2218.     end
  2219.  
  2220.   end # Html4Fr
  2221.  
  2222.  
  2223.   # Creates a new CGI instance.
  2224.   #
  2225.   # +type+ specifies which version of HTML to load the HTML generation
  2226.   # methods for.  The following versions of HTML are supported:
  2227.   #
  2228.   # html3:: HTML 3.x
  2229.   # html4:: HTML 4.0
  2230.   # html4Tr:: HTML 4.0 Transitional
  2231.   # html4Fr:: HTML 4.0 with Framesets
  2232.   #
  2233.   # If not specified, no HTML generation methods will be loaded.
  2234.   #
  2235.   # If the CGI object is not created in a standard CGI call environment
  2236.   # (that is, it can't locate REQUEST_METHOD in its environment), then
  2237.   # it will run in "offline" mode.  In this mode, it reads its parameters
  2238.   # from the command line or (failing that) from standard input.  Otherwise,
  2239.   # cookies and other parameters are parsed automatically from the standard
  2240.   # CGI locations, which varies according to the REQUEST_METHOD.
  2241.   def initialize(type = "query")
  2242.     if defined?(MOD_RUBY) && !ENV.key?("GATEWAY_INTERFACE")
  2243.       Apache.request.setup_cgi_env
  2244.     end
  2245.  
  2246.     extend QueryExtension
  2247.     @multipart = false
  2248.     if defined?(CGI_PARAMS)
  2249.       warn "do not use CGI_PARAMS and CGI_COOKIES"
  2250.       @params = CGI_PARAMS.dup
  2251.       @cookies = CGI_COOKIES.dup
  2252.     else
  2253.       initialize_query()  # set @params, @cookies
  2254.     end
  2255.     @output_cookies = nil
  2256.     @output_hidden = nil
  2257.  
  2258.     case type
  2259.     when "html3"
  2260.       extend Html3
  2261.       element_init()
  2262.       extend HtmlExtension
  2263.     when "html4"
  2264.       extend Html4
  2265.       element_init()
  2266.       extend HtmlExtension
  2267.     when "html4Tr"
  2268.       extend Html4Tr
  2269.       element_init()
  2270.       extend HtmlExtension
  2271.     when "html4Fr"
  2272.       extend Html4Tr
  2273.       element_init()
  2274.       extend Html4Fr
  2275.       element_init()
  2276.       extend HtmlExtension
  2277.     end
  2278.   end
  2279.  
  2280. end   # class CGI
  2281.